6.8.2 Style Files

Style files are Emacs Lisp files which are evaluated by AUCTeX in association with the \documentclass and \usepackage commands of a document (see Style Files). Support for RefTeX in such a style file is useful when the LaTeX style defines macros or environments connected with labels, citations, or the index. Many style files (e.g. amsmath.el or natbib.el) distributed with AUCTeX already support RefTeX in this way.

Before calling a RefTeX function, the style hook should always test for the availability of the function, so that the style file will also work for people who do not use RefTeX.

Additions made with style files in the way described below remain local to the current document. For example, if one package uses AMSTeX, the style file will make RefTeX switch over to \eqref, but this will not affect other documents.

A style hook may contain calls to reftex-add-label-environments¹ which defines additions to reftex-label-alist. The argument taken by this function must have the same format as reftex-label-alist. The amsmath.el style file of AUCTeX for example contains the following:

     (TeX-add-style-hook "amsmath"
        (lambda ()
          (if (fboundp 'reftex-add-label-environments)
              (reftex-add-label-environments '(AMSTeX)))))

while a package myprop defining a proposition environment with \newtheorem might use

     (TeX-add-style-hook "myprop"
        (lambda ()
          (LaTeX-add-environments '("proposition" LaTeX-env-label))
          (if (fboundp 'reftex-add-label-environments)
              (reftex-add-label-environments
               '(("proposition" ?p "prop:" "~\\ref{%s}" t
                                ("Proposition" "Prop.") -3))))))

Similarly, a style hook may contain a call to reftex-set-cite-format to set the citation format. The style file natbib.el for the Natbib citation style does switch RefTeX's citation format like this:

     (TeX-add-style-hook "natbib"
        (lambda ()
          (if (fboundp 'reftex-set-cite-format)
              (reftex-set-cite-format 'natbib))))

The hook may contain a call to reftex-add-index-macros to define additional \index-like macros. The argument must have the same format as reftex-index-macros. It may be a symbol, to trigger support for one of the builtin index packages. For example, the style multind.el contains

     (TeX-add-style-hook "multind"
       (lambda ()
         (and (fboundp 'reftex-add-index-macros)
              (reftex-add-index-macros '(multind)))))

If you have your own package myindex which defines the following macros to be used with the LaTeX index.sty file

     \newcommand{\molec}[1]{#1\index{Molecules!#1}}
     \newcommand{\aindex}[1]{#1\index[author]{#1}

you could write this in the style file myindex.el:

     (TeX-add-style-hook "myindex"
        (lambda ()
          (TeX-add-symbols
           '("molec" TeX-arg-index)
           '("aindex" TeX-arg-index))
          (if (fboundp 'reftex-add-index-macros)
              (reftex-add-index-macros
               '(("molec{*}" "idx" ?m "Molecules!" nil nil)
                 ("aindex{*}" "author" ?a "" nil nil))))))

Finally the hook may contain a call to reftex-add-section-levels to define additional section statements. For example, the FoilTeX class has just two headers, \foilhead and \rotatefoilhead. Here is a style file foils.el that will inform RefTeX about these:

     (TeX-add-style-hook "foils"
        (lambda ()
          (if (fboundp 'reftex-add-section-levels)
              (reftex-add-section-levels '(("foilhead" . 3)
                                           ("rotatefoilhead" . 3))))))